'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DDI_PROP_OP 9F "Jan 16, 2006"
.SH NAME
ddi_prop_op, ddi_getprop, ddi_getlongprop, ddi_getlongprop_buf, ddi_getproplen
\- get property information for leaf device drivers
.SH SYNOPSIS
.nf
#include <sys/types.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBddi_prop_op\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBddi_prop_op_t\fR \fIprop_op\fR,
     \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_getprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR,
      \fBint\fR \fIdefvalue\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_getlongprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR,
      \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_getlongprop_buf\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR,
     \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_getproplen\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR,
      \fBint *\fR\fIlengthp\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI). The \fBddi_getlongprop()\fR,
\fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR
functions are obsolete. Use \fBddi_prop_lookup\fR(9F) instead of
\fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, and
\fBddi_getproplen()\fR. Use \fBddi_prop_get_int\fR(9F) instead of
\fBddi_getprop()\fR
.SH PARAMETERS
.ne 2
.na
\fB\fIdev\fR\fR
.ad
.RS 12n
Device number associated with property or \fBDDI_DEV_T_ANY\fR as the
\fIwildcard\fR device number.
.RE

.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 12n
Pointer to a device info node.
.RE

.sp
.ne 2
.na
\fB\fIprop_op\fR\fR
.ad
.RS 12n
Property operator.
.RE

.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 12n
Possible flag values are some combination of:
.sp
.ne 2
.na
\fB\fBDDI_PROP_DONTPASS\fR\fR
.ad
.RS 21n
do not pass request to parent device information node if property not found
.RE

.sp
.ne 2
.na
\fB\fBDDI_PROP_CANSLEEP\fR\fR
.ad
.RS 21n
the routine may sleep while allocating memory
.RE

.sp
.ne 2
.na
\fB\fBDDI_PROP_NOTPROM\fR\fR
.ad
.RS 21n
do not look at PROM properties (ignored on architectures that do not support
PROM properties)
.RE

.RE

.sp
.ne 2
.na
\fB\fIname\fR\fR
.ad
.RS 12n
String containing the name of the property.
.RE

.sp
.ne 2
.na
\fB\fIvaluep\fR\fR
.ad
.RS 12n
If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF\fR, this should be a pointer to the
users buffer. If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC,\fR this should be
the \fIaddress\fR of a pointer.
.RE

.sp
.ne 2
.na
\fB\fIlengthp\fR\fR
.ad
.RS 12n
On exit, \fI*lengthp\fR will contain the property length. If \fIprop_op\fR is
\fBPROP_LEN_AND_VAL_BUF\fR then before calling \fBddi_prop_op()\fR,
\fIlengthp\fR should point to an \fBint\fR that contains the length of callers
buffer.
.RE

.sp
.ne 2
.na
\fB\fIdefvalue\fR\fR
.ad
.RS 12n
The value that \fBddi_getprop()\fR returns if the property is not found.
.RE

.SH DESCRIPTION
The \fBddi_prop_op()\fR function gets arbitrary-size properties for leaf
devices. The routine searches the device's property list. If it does not find
the property at the device level, it examines the \fIflags\fR argument, and if
\fBDDI_PROP_DONTPASS\fR is set, then \fBddi_prop_op()\fR returns
\fBDDI_PROP_NOT_FOUND.\fR Otherwise, it passes the request to the next level of
the device info tree. If it does find the property, but the property has been
explicitly undefined, it returns \fBDDI_PROP_UNDEFINED.\fR Otherwise it returns
either the property length, or both the length and value of the property to the
caller via the \fIvaluep\fR and \fIlengthp\fR pointers, depending on the value
of \fIprop_op\fR, as described below, and returns \fBDDI_PROP_SUCCESS.\fR If a
property cannot be found at all, \fBDDI_PROP_NOT_FOUND\fR is returned.
.sp
.LP
Usually, the \fIdev\fR argument should be set to the actual device number that
this property applies to.  However, if the \fIdev\fR argument is
\fBDDI_DEV_T_ANY,\fR the \fIwildcard dev\fR, then \fBddi_prop_op()\fR will
match the request based on \fIname\fR only (regardless of the actual \fIdev\fR
the property was created with). This property/dev match is done according to
the property search order which is to first search software properties created
by the driver in \fIlast-in, first-out\fR (LIFO) order, next search software
properties created by the \fIsystem\fR in LIFO order, then search PROM
properties if they exist in the system architecture.
.sp
.LP
Property operations are specified by the \fIprop_op\fR argument. If
\fIprop_op\fR is \fBPROP_LEN,\fR then \fBddi_prop_op()\fR just sets the callers
length, \fI*lengthp,\fR to the property length and returns the value
\fBDDI_PROP_SUCCESS\fR to the caller. The \fIvaluep\fR argument is not used in
this case.  Property lengths are \fB0\fR for boolean properties,
\fBsizeof\|(int)\fR for integer properties, and size in bytes for long
(variable size) properties.
.sp
.LP
If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF,\fR then \fIvaluep\fR should be a
pointer to a user-supplied buffer whose length should be given in
\fI*lengthp\fR by the caller.  If the requested property exists,
\fBddi_prop_op()\fR first sets \fI*lengthp\fR to the property length.  It then
examines the size of the buffer supplied by the caller, and if it is large
enough, copies the property value into that buffer, and returns
\fBDDI_PROP_SUCCESS.\fR If the named property exists but the buffer supplied is
too small to hold it, it returns \fBDDI_PROP_BUF_TOO_SMALL.\fR
.sp
.LP
If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC,\fR and the property is found,
\fBddi_prop_op()\fR sets \fI*lengthp\fR to the property length. It then
attempts to allocate a buffer to return to the caller using the
\fBkmem_alloc\fR(9F) routine, so that memory can be later recycled using
\fBkmem_free\fR(9F). The driver is expected to call \fBkmem_free()\fR with the
returned address and size when it is done using the allocated buffer. If the
allocation is successful, it sets \fI*valuep\fR to point to the allocated
buffer, copies the property value into the buffer and returns
\fBDDI_PROP_SUCCESS.\fR Otherwise, it returns \fBDDI_PROP_NO_MEMORY.\fR Note
that the \fIflags\fR argument may affect the behavior of memory allocation in
\fBddi_prop_op()\fR. In particular, if \fBDDI_PROP_CANSLEEP\fR is set, then the
routine will wait until memory is available to copy the requested property.
.sp
.LP
The \fBddi_getprop()\fR function returns boolean and integer-size properties.
It is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
\fBPROP_LEN_AND_VAL_BUF\fR, and the buffer is provided by the wrapper. By
convention, this function returns a \fB1\fR for boolean (zero-length)
properties.
.sp
.LP
The \fBddi_getlongprop()\fR function returns arbitrary-size properties. It is a
convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
\fBPROP_LEN_AND_VAL_ALLOC,\fR so that the routine will allocate space to hold
the buffer that will be returned to the caller via \fI*valuep\fR.
.sp
.LP
The \fBddi_getlongprop_buf()\fR function returns arbitrary-size properties. It
is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
\fBPROP_LEN_AND_VAL_BUF\fR so the user must supply a buffer.
.sp
.LP
The \fBddi_getproplen()\fR function returns the length of a given property. It
is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
\fBPROP_LEN\fR.
.SH RETURN VALUES
The \fBddi_prop_op()\fR, \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR,
and \fBddi_getproplen()\fR functions return:
.sp
.ne 2
.na
\fB\fBDDI_PROP_SUCCESS\fR\fR
.ad
.RS 26n
Property found and returned.
.RE

.sp
.ne 2
.na
\fB\fBDDI_PROP_NOT_FOUND\fR\fR
.ad
.RS 26n
Property not found.
.RE

.sp
.ne 2
.na
\fB\fBDDI_PROP_UNDEFINED\fR\fR
.ad
.RS 26n
Property already explicitly undefined.
.RE

.sp
.ne 2
.na
\fB\fBDDI_PROP_NO_MEMORY\fR\fR
.ad
.RS 26n
Property found, but unable to allocate memory. \fIlengthp\fR points to the
correct property length.
.RE

.sp
.ne 2
.na
\fB\fBDDI_PROP_BUF_TOO_SMALL\fR\fR
.ad
.RS 26n
Property found, but the supplied buffer is too small. \fIlengthp\fR points to
the correct property length.
.RE

.sp
.LP
The \fBddi_getprop()\fR function returns:
.sp
.LP
The value of the property or the value passed into the routine as
\fIdefvalue\fR if the property is not found. By convention, the value of zero
length properties (boolean properties) are returned as the integer value 1.
.SH CONTEXT
These functions can be called from user, interrupt, or kernel context, provided
\fBDDI_PROP_CANSLEEP\fR is not set; if it is set, they cannot be called from
interrupt context.
.SH ATTRIBUTES
See \fBattributes\fR(7) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Stability Level	T{
\fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR functions are Obsolete
T}
.TE

.SH SEE ALSO
.BR attributes (7),
.BR ddi_prop_create (9F),
.BR ddi_prop_get_int (9F),
.BR ddi_prop_lookup (9F),
.BR kmem_alloc (9F),
.BR kmem_free (9F)
.sp
.LP
\fIWriting Device Drivers\fR
